#pragma once // 防止头文件被重复包含

#include "stdint.h"  // 标准整数类型定义
#include "esp_err.h" // ESP32错误码定义

#ifdef __cplusplus
extern "C"
{ // 如果是C++环境，使用C语言链接规范
#endif

    /**
     * @brief 逻辑分析仪回调函数类型定义
     *
     * @param samle_buf    - 采样数据缓冲区指针，包含采集到的数字信号数据
     * @param samples      - 采样点数，根据采样宽度可能是4/8/16位字
     * @param sample_rate  - 实际采样率(Hz)
     * @param channels     - 实际测量的通道数量
     * 注意：如果任何参数为0表示检测到超时
     */
    typedef void (*logic_analyzer_cb_t)(uint8_t *samle_buf, int samples, int sample_rate, int channels);

    /**
     * @brief 逻辑分析仪配置结构体
     * 用于配置逻辑分析仪的各项参数
     */
    typedef struct
    {
        int pin[16]; // GPIO引脚配置数组:
                     // ESP32: 0-39, ESP32S3: 0-48
                     // -1表示禁用该通道
                     // 8位模式下使用前8个引脚[0-7]

        int pin_trigger; // 触发引脚GPIO编号，-1表示禁用触发功能

        int trigger_edge; // 触发边沿类型:
                          // POS_EDGE(上升沿)/NEG_EDGE(下降沿)/ANY_EDGE(任意边沿)

        int number_of_samples; // 采样点数(根据采样宽度可能是8/16位字)

        int sample_rate; // 采样率(Hz)，范围5000-80000000，具体取决于:
                         // 目标芯片、采样宽度和是否使用PSRAM

        int number_channels; // 测量通道数量:
                             // ESP32: 8-16通道
                             // ESP32S3: 8或16通道
                             // ESP32C3: 1/2/4通道

        int samples_to_psram; // 是否保存采样数据到PSRAM:
                              // 0-使用RAM, 1-使用PSRAM(ESP32S3支持)

        int meashure_timeout; // 最大测量时间(FreeRTOS Tick数)
                              // 如果设为0，超时后停止并重置逻辑分析仪

        logic_analyzer_cb_t logic_analyzer_cb; // 采样完成后的回调函数指针
    } logic_analyzer_config_t;

    /**
     * @brief 硬件参数结构体
     * 用于获取和返回逻辑分析仪的硬件能力参数
     */
    typedef struct
    {
        int max_channels;     // 输出 - 目标芯片支持的最大通道数
        int min_channels;     // 输出 - 目标芯片支持的最小通道数
        int max_sample_rate;  // 输出 - 当前配置下的最大采样率(考虑通道数和PSRAM使用情况)
        int min_sample_rate;  // 输出 - 当前配置下的最小采样率
        int max_sample_cnt;   // 输出 - 最大采样点数(考虑目标芯片、PSRAM和可用内存)
        int min_sample_cnt;   // 输出 - 最小采样点数(考虑目标芯片和PSRAM)
        int available_psram;  // 输出 - 是否可用PSRAM: 1-可用, 0-不可用
        int current_psram;    // 输入/输出 - 是否使用PSRAM:
                              // 输入值超出范围时返回最小可用配置
        int current_channels; // 输入/输出 - 当前通道数:
                              // 输入值超出范围时返回最小可用通道数
    } logic_analyzer_hw_param_t;

    /**
     * @brief 获取逻辑分析仪硬件参数
     *
     * 根据目标芯片、可用内存、PSRAM状态和通道数配置，获取逻辑分析仪的硬件能力参数
     *
     * @param hw 输入/输出参数结构体指针
     *           需要预先设置current_psram和current_channels字段
     *
     * @return 执行状态:
     *     - ESP_OK                 成功
     *     - ESP_ERR_INVALID_ARG    参数错误
     *     - ESP_FAIL               初始化失败
     */
    esp_err_t logic_analyzer_get_hw_param(logic_analyzer_hw_param_t *hw);

    /**
     * @brief 启动逻辑分析仪
     *
     * 根据配置参数启动逻辑分析仪进行信号采集
     *
     * @param config 逻辑分析仪配置结构体指针
     *
     * @return 执行状态:
     *     - ESP_OK                 成功
     *     - ESP_ERR_INVALID_ARG    参数错误
     *     - ESP_ERR_NO_MEM         内存不足无法初始化
     *     - ESP_ERR_INVALID_STATE  逻辑分析仪已在运行状态
     *     - ESP_FAIL               初始化失败
     */
    esp_err_t start_logic_analyzer(logic_analyzer_config_t *config);

#ifdef __cplusplus
} // 结束extern "C"块
#endif